Fix internal map paths in coop mission .scmap files on deploy - #328

The problem

getFileContent() rewrites /maps/<folder>/ into /maps/<folder>.vNNNN/ for text files
only. The paths embedded in the .scmap binary are not touched, so after a release they
still point at the unversioned folder. The missions that ship their own terrain textures or
decals lose them — the map loads with missing textures.

Three commits: the fix, a check that the release is intact before it is written, and a CI
job so the path rewriting cannot break unnoticed later.

1. The fix

ScmapPathFixer.kt reads a .scmap and writes it back byte for byte, inserting the
release version into the map folder segment of every embedded path. It is a port of
fix_paths from @speed2's sc_map_parser.gd, the script these paths are repaired with by
hand today.

CoopMapDeployer.getFileContent() calls it for .scmap files. Nothing else changes — the
version still comes from coop_map.version + 1, change detection and zip building work as
before, and build.gradle.kts needs no new source entry because kotlin.srcDirs(".")
picks the file up.

Only the mission's own folder is versioned

A path is rewritten only when its folder segment equals the mission folder. This is not
cosmetic — versioning everything under /maps/ would break released missions:

• 13 missions point at a base game map, e.g. FAF_Coop_Fort_Clarke_Assault uses
  map = '/maps/X1CA_001/X1CA_001.scmap'. Those are exactly the missions whose repo
  .scmap is the 18 byte test fake map file placeholder.
• FAF_Coop_Operation_Red_Revenge references a vault map from inside its binary:
  /maps/seraphim outpost ep.v0002/skycube_tundra02a.dds. Blindly appending would produce
  …ep.v0002.v0003.

Paths that lead somewhere else are left alone and logged at WARN. An already present
.vNNNN on the mission's own folder is replaced rather than appended to, so a re-run
cannot stack suffixes.

Nothing is parsed without a reason

Before parsing, a raw case-insensitive byte scan looks for /maps/<own folder>. Only maps
that actually reference their own folder are parsed at all — 4 of 31 real map files. The
placeholders never reach the parser, and neither do the 27 maps that only use base game
textures.

2. Verification before the release is written

The rewriter checks itself: the byte delta has to match the bytes added to paths, and the
rewritten file has to parse again and reproduce itself. Both catch a structural mistake,
neither catches a semantic one — an off by one on the version, or the wrong folder name,
would pass both and ship a map with missing textures that nothing downstream notices.

verifyRelease() closes that gap. It resolves every path the fixer rewrote against the
files that actually end up in the zip. If one does not resolve, the mission is not
deployed: no zip, no database update, the previous version stays in place, and the other
missions carry on.

Run against the current missions with the rewriting skipped — that is, the bug this PR
fixes — the check flags all 40 rewritten paths as broken. It would have caught the original
problem on its own.

References in text files are only reported, not enforced. Three of them have been broken
for years — two typos in comment headers, one stale hardcoded scca_coop_r06.v0018 — and
failing on those would block releases for cosmetic reasons.

The zip is also written to <name>.part and moved into place afterwards, so a failure
midway cannot leave a half written archive in the directory maps are served from.

3. CI

gradle verifyScmapFixer runs the fixer over every mission in a faf-coop-maps checkout,
in the same gradle:9.4-jdk21 image the CronJobs use. The workflow only triggers when
apps/faf-legacy-deployment/scripts/** changes.

The load bearing assertion is the identity check: rewriting with a negative version has to
reproduce the input byte for byte. It runs over all missions, not only the four that
need the fix, so it covers the old file formats too. The coop missions use three of them —
v53 (16 missions), v56 (14) and v60 (1) — and scoping a section to the wrong version breaks
exactly those and nothing else. That is not hypothetical: it is the mistake an earlier port
of this parser made, and only a test across all formats catches it.

Effect on the next release

Their checksums change, so these four get one version bump on the first run after this
lands. The other 38 missions are byte identical and are skipped as before. If a dry run
reports more than these four as changed, something is wrong — unless MAP_DIR is empty, in
which case everything counts as changed because there are no old zips to compare against.

What is deployed today

Checked against the content server rather than assumed: the live
faf_coop_operation_blockade.v0004 and faf_coop_operation_tha_atha_aez.v0015 each contain
a .scmap that is MD5 identical to the unfixed one in this repo, and their embedded paths
still point at the unversioned folder. No path corrected coop map has ever been
deployed. The manual repairs circulate as files and never went back into the pipeline. An
earlier revision of this description claimed the live .v0004 was the corrected one and
that this PR reproduces it, which was wrong.

Verification

Three checks, in increasing order of what they prove.

The CI job, over all 44 map files in a faf-coop-maps checkout. Rewriting with a
negative version reproduces every one of the 31 real ones byte for byte, the 13 placeholders
are skipped, exactly four missions are detected as needing the fix, and the format versions
present are v53 (16), v56 (14) and v60 (1).

Byte comparison against the Coop-Discord maps. Running the fixer over the repo files at the version each repair was
made for:

Identical size, identical paths, and across roughly 60 MB of binary every single differing
byte is an ASCII case flip. Nothing structural differs, across all three format versions.

In the running game. The three affected missions that were installed locally were
deleted, downloaded again through the client, confirmed byte identical to the repo files,
and the missing textures were visible. Swapping in the output of ScmapPathFixer at the same
version and relaunching: FAF_Coop_Operation_Blockade, FAF_Coop_Operation_Tha_Atha_Aez and
FAF_Coop_Operation_Overlord_Surth_Velsok all render every texture, with no regression.

That last check also covers both string encodings in the format. The terrain texture paths of
Blockade and Tha_Atha_Aez are null terminated; the two decals of Overlord are the length
prefixed kind, which is a different branch of the rewriter.

The one deliberate divergence from fix_paths

fix_paths lower cases the whole path, this lower cases only the /maps/<folder>.vNNNN
head. That accounts for all 199 differing bytes in the table above, and for nothing else.

It does not change what the engine finds. gpg::STR_CanonizeFilename lower cases every path
before a lookup, the zip entry index is keyed by gpg::STR_CompareNoCase, and a game log
shows a directory named 12 Fields of Isis V13 being mounted as
/maps/12 fields of isis v13/. Keeping the tail as it is means paths that already match
their files on disk stay matching, which is the case for the four decal paths of
Golden_Crystals and Overlord_Surth_Velsok.

Out of scope

• Automatic deployment on a git release (the next step).
• The hardcoded coopMaps list — FAF_Coop_Seabring_Defense and FAF_Coop_Theban_Colony
  are in the repo but not in the list.
• FAF_Coop_Operation_Red_Revenge: its skycube points at another map while the .dds sits
  in its own folder. Left as is here, since that is a decision about the map, not about the
  deployment.

Summary by CodeRabbit

• New Features

  • Added automatic versioning for mission asset paths during coop map deployment.
  • Added release verification to confirm packaged map references resolve correctly.
  • Expanded validation for map and text-file references.

• Bug Fixes

  • Improved archive creation reliability by preventing incomplete ZIP files from replacing valid releases.
  • Preserved external asset references while updating paths belonging to the deployed mission.
  • Deployment now reports failures clearly and exits unsuccessfully when a mission cannot be deployed.

• Tests

  • Added automated checks for path rewriting and release package integrity.